Add `<LinkButton>` component #1784

HiDeoo · 2024-04-25T11:01:35Z

What kind of changes does this PR include?

Changes or translations of Starlight docs site content
Changes to Starlight code

Description

This PR adds a new <LinkButton> component adressing the request in the built-in components discussion.

Preview playground page: https://starlight-git-fork-hideoo-hd-feat-link-button-astrodotbuild.vercel.app/guides/components/#link-buttons

Visually, this is almost identical to the internal <CallToAction> component (now removed and replaced by the new component) that was used for actions in the hero component.

The name is still up for discussion, some design system use CTALink or CallToAction but this may not be obvious to everyone. Some others use ButtonLink but as pointed out by Chris, we already have a <LinkCard> component so this uses the same pattern.
Using something like <Button> may be confusing as this is a link that should be used for navigation and not a form primitive for example.

Remaining tasks

Remove demo style (docs/src/assets/landing.css)
Remove demo page (docs/src/content/docs/reference/link-button.mdx)

…on>` component

changeset-bot · 2024-04-25T11:01:39Z

🦋 Changeset detected

Latest commit: 5ea0fc5

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@astrojs/starlight	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

astrobot-houston · 2024-04-25T11:02:08Z

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

Locale	File	Note
en	guides/components.mdx	Source changed, localizations will be marked as outdated.
en	index.mdx	Source changed, localizations will be marked as outdated.
en	reference/frontmatter.md	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

HiDeoo · 2024-04-25T11:02:16Z

packages/starlight/style/markdown.css

+.sl-markdown-content a:not(:where(:is(.not-content, .not-content *))) {
 	color: var(--sl-color-text-accent);
 }
-.sl-markdown-content a:hover:not(:where(.not-content *)) {
+.sl-markdown-content a:hover:not(:where(:is(.not-content, .not-content *))) {


These changes are used to avoid <LinkButton> getting Markdown link styles applied to it by specifying the not-content class on the link itself and not a wrapping element.

I'm wondering if this is a change that could be applied to some other places to avoid relying on a wrapping element to avoid Markdown styles 🤔

I’d like to avoid this if we can to avoid introducing inconsistencies.

The main reason .not-content applies to children not the element with the class is due to spacing. Consider an example like this:

<p>Lorem ipsum...</p> <div class="not-content">Some non-content...</div> <p>Dolor sic...</p>

If not-content removed the margin styles from the <div> in this example, it would end up squished next to the first paragraph.

I have sometimes considered whether we should have separate rules for escaping spacing vs other styles, but I’m not sure that’s particularly easy to understand or communicate.

What would be better would be to either give the Markdown styles a lower specificity (e.g. wrap each selector in :where() maybe?) or move forward with the @layer refactor. That would make it less painful for user components (or our own in this case) to escape the default styles without the extra not-content class. (not-content would still be needed for circumstances that benefit from a full reset, but there wouldn’t be the temptation to use it because otherwise !important is needed to enforce a component style.)

Thanks, this makes sense, in this case this was a link color only change but there is no guarantee this would stay the same any way. I think in this case, we should be able to just specify the color in the various selectors, e.g. .sl-link-button.primary, .sl-link-button.secondary, and .sl-link-button.minimal.

…mary`

HiDeoo · 2024-04-29T10:23:51Z

Following the last Talking & Doc'ing session discussions, I updated the pull request to include the following changes:

The <LinkButton> variant now defaults to primary instead of minimal.
The hero component action button variant now defaults to primary instead of minimal.

* main: (57 commits) Add type checking job to the CI workflow (withastro#1827) [ci] format i18n(pt-BR): Update `components.mdx` (withastro#1815) [ci] format i18n(ru): update translations (withastro#1825) i18n(pt-BR): Update `css-and-tailwind.mdx` (withastro#1817) i18n(es): updates `pages` (withastro#1823) i18n(es): update `i18n` (withastro#1822) i18n(es): updates `overrides` (withastro#1820) i18n(es): update `guides/components` and add `syncKey` to various pages (withastro#1818) [ci] format i18n(es): update `community-content` (withastro#1824) i18n(es): update `configuration` (withastro#1821) i18n(es): update `frontmatter` (withastro#1819) i18n(fr): update `guides/pages.mdx` (withastro#1800) i18n(fr): update `reference/overrides.md` (withastro#1803) i18n(fr): update `reference/frontmatter.md` (withastro#1802) i18n(fr): update `reference/configuration.mdx` (withastro#1801) i18n(fr): update `guides/i18n.mdx` (withastro#1799) i18n(fr): update `guides/components` and add `syncKey` to various pages (withastro#1797) ...

lorenzolewis · 2024-06-05T19:30:14Z

packages/starlight/package.json

@@ -51,10 +51,6 @@
      "types": "./components/Sidebar.astro.tsx",
      "import": "./components/Sidebar.astro"
    },
-    "./components/CallToAction.astro": {


May want to call this out in the changeset as well

lorenzolewis · 2024-06-05T19:42:39Z

One additional thing: Not sure if you were basing this off of the Figma file or not, but how about links without any text and only an icon? Is that something you wanted to support in this?

delucis

Thanks again for the PR @HiDeoo and apologies for the belated review — I left some comments!

how about links without any text and only an icon? Is that something you wanted to support in this?

Regarding this comment from @lorenzolewis, I think it’s OK not to support that for now. I’m not 100% sure what the intended usage was for icon buttons in Figma and they complicate things somewhat — icon-only buttons still need an accessible label etc. Also, might be possible to work around for someone who really needs it:

<LinkButton href="/astro" icon="astro">
  <span class="sr-only">Astro</span>
</LinkButton>

.changeset/thirty-students-sit.md

docs/src/content/docs/guides/components.mdx

delucis · 2024-08-05T14:20:41Z

packages/starlight/style/markdown.css

+.sl-markdown-content a:not(:where(:is(.not-content, .not-content *))) {
 	color: var(--sl-color-text-accent);
 }
-.sl-markdown-content a:hover:not(:where(.not-content *)) {
+.sl-markdown-content a:hover:not(:where(:is(.not-content, .not-content *))) {


I’d like to avoid this if we can to avoid introducing inconsistencies.

The main reason .not-content applies to children not the element with the class is due to spacing. Consider an example like this:

<p>Lorem ipsum...</p> <div class="not-content">Some non-content...</div> <p>Dolor sic...</p>

If not-content removed the margin styles from the <div> in this example, it would end up squished next to the first paragraph.

I have sometimes considered whether we should have separate rules for escaping spacing vs other styles, but I’m not sure that’s particularly easy to understand or communicate.

What would be better would be to either give the Markdown styles a lower specificity (e.g. wrap each selector in :where() maybe?) or move forward with the @layer refactor. That would make it less painful for user components (or our own in this case) to escape the default styles without the extra not-content class. (not-content would still be needed for circumstances that benefit from a full reset, but there wouldn’t be the temptation to use it because otherwise !important is needed to enforce a component style.)

packages/starlight/user-components/LinkButton.astro

delucis · 2024-08-05T14:47:21Z

packages/starlight/user-components/LinkButton.astro

+	:global(.sl-markdown-content) .sl-link-button {
+		margin-inline-end: 0.5em;
+	}
+	:global(.sl-markdown-content) .sl-link-button:not(:where(p *)) {
+		margin-block: 1rem;
+	}


This makes me a bit nervous, but I guess it’s OK 😅

I don’t love the context-specific styling, but I also thought about it a bit and can see that without this, the default behaviour would feel pretty broken. Other solutions I can think of are also annoying, so we should probably go with this.

delucis · 2024-08-05T14:54:00Z

docs/src/content/docs/guides/components.mdx

+
+<LinkButton href="/getting-started/">Get started</LinkButton>
+<LinkButton href="https://docs.astro.build" variant="secondary" icon="external">
+	Related: Astro


Noting that this renders as <a ...><p>Related: Astro</p></a>

Not sure if there’s anything we could or should do about that? It’s not invalid HTML and I guess doesn’t really have any bad side effects.

* main: (275 commits) [ci] release (withastro#2165) Define well-known RTL locales before calling `getLocaleInfo()` for default locale (withastro#2167) Update dependencies (withastro#2166) Improve page load performance (withastro#2155) docs: Add CodeSweetly to showcase (withastro#2160) [ci] release (withastro#2145) Fix bug for projects with spaces in their pathname (withastro#2156) ci: update file icons (withastro#2157) [ci] format Merge <link rel="canonical" /> tags, quick fixes (withastro#2153) (withastro#2154) Add two new showcase sites (withastro#2149) [ci] format i18n(zh-cn): Update `environmental-impact.md` (withastro#2148) add Saasfly showcase (withastro#2147) docs: add 'og:image:alt' metadata (withastro#2143) Deleting unnecessary twitter meta tags, quick fixes (withastro#2137) [ci] format i18n(es): update `environmental-impact` (withastro#2144) [ci] release (withastro#2142) feat: Add Pinterest icon to social list (withastro#2135) ...

Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com>

netlify · 2024-08-06T13:05:54Z

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	`5ea0fc5`
🔍 Latest deploy log	https://app.netlify.com/sites/astro-starlight/deploys/66be511fecd4440008220a39
😎 Deploy Preview	https://deploy-preview-1784--astro-starlight.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 100 (no change from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 92 (no change from production) PWA: - View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify site configuration.

HiDeoo · 2024-08-06T13:10:34Z

Updated the branch and push a few changes that should address all the great feedback, thanks for the review 🙌

I also temporarily added back the demo page, it was useful to me to get back into the context of the PR so thought I might as well include it in case it can help and I'll remove it later (also unticked the associated todo in the PR body).

delucis

Thanks for the updates @HiDeoo — left a couple more comments now I had the preview page to play with, but I think it looks pretty close to being ready 🙌

packages/starlight/user-components/LinkButton.astro

Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com>

delucis

I think we’re ready as far as I’m concerned — thank you!

Re: spacing on mobile vs desktop, I see what you mean, but I still think it will look OK in context. One of the slightly tricky things about the demo page is that there are buttons everywhere, but hopefully in reality people will only be using one or two 😁

docs/src/content/docs/reference/link-button.mdx

delucis

I declare this <LinkButton> seaworthy — anchors away! 🚢

HiDeoo added 5 commits April 24, 2024 16:57

feat: add basic <LinkButton> component

e6ba3b4

chore: update examples

ed168b5

feat: replace <CallToAction> internal component with new `<LinkButt…

f9cd54c

…on>` component

docs: add <LinkButton> documentation

50359b3

chore: add changeset

93b2de1

This comment was marked as outdated.

Sign in to view

github-actions bot added 📚 docs Documentation website changes 🌟 core Changes to Starlight’s main package labels Apr 25, 2024

HiDeoo commented Apr 25, 2024

View reviewed changes

vercel bot deployed to Preview – starlight April 25, 2024 11:03 View deployment

chore: fix rtl example

e273047

vercel bot deployed to Preview – starlight April 25, 2024 11:14 View deployment

HiDeoo added 2 commits April 29, 2024 12:12

refactor: change hero component action button default variant to `pri…

bf281c7

…mary`

refactor: change <LinkButton> default variant to primary

15580a8

vercel bot deployed to Preview – starlight April 29, 2024 10:22 View deployment

HiDeoo added 4 commits May 3, 2024 12:13

chore: improve a11y of custom class example

0a8be2f

fix: ensure consistent link button heights

71c7460

chore: remove demo page

54beb60

vercel bot deployed to Preview – starlight May 3, 2024 14:11 View deployment

lorenzolewis reviewed Jun 5, 2024

View reviewed changes

delucis reviewed Aug 5, 2024

View reviewed changes

HiDeoo and others added 4 commits August 6, 2024 14:30

docs: add back demo page

4e05716

fix: revert markdown styles .not-content changes

1365678

fix: changeset typo

3ede8d9

Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com>

HiDeoo and others added 3 commits August 6, 2024 14:40

docs: apply wording improvement suggestions

45a3194

Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com>

feat: improve outline visibility

da2e714

fix: reduce link button heights

fca5a8f

delucis reviewed Aug 6, 2024

View reviewed changes

packages/starlight/user-components/LinkButton.astro Outdated Show resolved Hide resolved

packages/starlight/user-components/LinkButton.astro Show resolved Hide resolved

feat: tweak link buttons spacing

761df6b

Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com>

delucis reviewed Aug 7, 2024

View reviewed changes

docs/src/content/docs/reference/link-button.mdx Outdated Show resolved Hide resolved

chore: remove demo page

ebc8dc1

delucis added the 🌟 minor Change that triggers a minor release label Aug 7, 2024

delucis approved these changes Aug 7, 2024

View reviewed changes

delucis mentioned this pull request Aug 11, 2024

fix: using wrong field to deconstruct in 'CallToAction' component #2182

Closed

Merge branch 'main' into hd-feat-link-button

5ea0fc5

delucis merged commit 68f56a7 into withastro:main Aug 16, 2024
16 checks passed

astrobot-houston mentioned this pull request Aug 16, 2024

[ci] release #2217

Merged

This was referenced Aug 16, 2024

i18n(fr): update index #2222

Merged

i18n(fr): update reference/frontmatter #2223

Merged

This was referenced Aug 17, 2024

i18n(ko-KR): update components.mdx #2225

Merged

i18n(ko-KR): update index.mdx #2229

Merged

i18n(ko-KR): update fontmatter.md #2231

Merged

This was referenced Aug 17, 2024

i18n(fr): update guides/components #2232

Merged

[i18nIgnore] docs: update index.mdx hero action buttons variants #2233

Merged

Update examples index hero button action variants #2234

Merged

This was referenced Aug 19, 2024

i18n(zh-cn): Update frontmatter.mdx #2239

Merged

i18n(zh-cn): Update components.mdx #2240

Merged

[i18nIgnore] Upgrade Starlight to 0.26.1 withastro/docs#9131

Merged

HiDeoo mentioned this pull request Aug 19, 2024

Components documentation improvements #2121

Draft

3 tasks

delucis mentioned this pull request Aug 21, 2024

Update index.mdx #2245

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add `<LinkButton>` component #1784

Add `<LinkButton>` component #1784

HiDeoo commented Apr 25, 2024 •

edited

Loading

This comment was marked as outdated.

changeset-bot bot commented Apr 25, 2024 •

edited

Loading

astrobot-houston commented Apr 25, 2024 •

edited

Loading

HiDeoo Apr 25, 2024

delucis Aug 5, 2024

HiDeoo Aug 6, 2024

HiDeoo commented Apr 29, 2024

lorenzolewis Jun 5, 2024

lorenzolewis commented Jun 5, 2024

delucis left a comment

delucis Aug 5, 2024

delucis Aug 5, 2024

delucis Aug 5, 2024

netlify bot commented Aug 6, 2024 •

edited

Loading

HiDeoo commented Aug 6, 2024

delucis left a comment

delucis left a comment

delucis left a comment

Add <LinkButton> component #1784

Add <LinkButton> component #1784

Conversation

HiDeoo commented Apr 25, 2024 • edited Loading

What kind of changes does this PR include?

Description

Remaining tasks

This comment was marked as outdated.

changeset-bot bot commented Apr 25, 2024 • edited Loading

🦋 Changeset detected

astrobot-houston commented Apr 25, 2024 • edited Loading

Lunaria Status Overview

Tracked Files

HiDeoo Apr 25, 2024

Choose a reason for hiding this comment

delucis Aug 5, 2024

Choose a reason for hiding this comment

HiDeoo Aug 6, 2024

Choose a reason for hiding this comment

HiDeoo commented Apr 29, 2024

lorenzolewis Jun 5, 2024

Choose a reason for hiding this comment

lorenzolewis commented Jun 5, 2024

delucis left a comment

Choose a reason for hiding this comment

delucis Aug 5, 2024

Choose a reason for hiding this comment

delucis Aug 5, 2024

Choose a reason for hiding this comment

delucis Aug 5, 2024

Choose a reason for hiding this comment

netlify bot commented Aug 6, 2024 • edited Loading

✅ Deploy Preview for astro-starlight ready!

HiDeoo commented Aug 6, 2024

delucis left a comment

Choose a reason for hiding this comment

delucis left a comment

Choose a reason for hiding this comment

delucis left a comment

Choose a reason for hiding this comment

Add `<LinkButton>` component #1784

Add `<LinkButton>` component #1784

HiDeoo commented Apr 25, 2024 •

edited

Loading

changeset-bot bot commented Apr 25, 2024 •

edited

Loading

astrobot-houston commented Apr 25, 2024 •

edited

Loading

netlify bot commented Aug 6, 2024 •

edited

Loading